<!DOCTYPE HTML PUBLIC "-//ORA//DTD CD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>[Chapter 7] 7.4 Documentation Comments</TITLE>
<META NAME="author" CONTENT="Mark Grand">
<META NAME="date" CONTENT="Thu Jul 31 13:15:44 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="java">
<META NAME="title" CONTENT="Java Language Reference">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java Language Reference" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch07_03.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 7<br>Program Structure</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch07_05.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JLR2-CH-7-SECT-4">7.4 Documentation Comments</A></h2>

<P CLASS=para>
<A NAME="CH07.DOC1"></A><A NAME="CH07.DOC2"></A><A NAME="CH07.DOC3"></A>Documentation comments are used to
create stand-alone documentation for classes. Documentation comments
are processed into Web pages by the <I CLASS=emphasis>javadoc</I>
program that is part of Sun's Java Development Kit (JDK).
The <I CLASS=emphasis>javadoc</I> program and the way that it processes
<I CLASS=emphasis>.java</I> files into Web pages is fully described
in the documentation for <I CLASS=emphasis>javadoc</I> provided by
Sun. The remainder of this section describes the special formatting
information that can be embedded in documentation comments.

<P CLASS=para>
Documentation comments are comments that begin with <tt CLASS=literal>/**</tt>.
If a documentation comment immediately precedes the declaration
of a class, interface, method, or field variable, it is assumed
to describe that class, interface, method, or field variable.

<P CLASS=para>
HTML tags can be included in
a documentation comment; they are passed directly to the generated
Web page. In addition to passing HTML tags, <I CLASS=emphasis>javadoc</I>
recognizes
special tags that start with an "at" sign (<tt CLASS=literal>@</tt>).
These tags must appear as the first word on a line in order to be
recognized. Here is an example of a documentation comment that includes
these special <I CLASS=emphasis>javadoc</I> tags:

<DIV CLASS=screen>
<P>
<PRE>
/**
 * RomanNumeral is a class similar to Integer, except that
 * it uses roman numerals for its string based
 * representation.  It only represents positive numbers.
 *
 * @see        Integer
 * @see        Number
 * @see        Float
 * @see        Double
 * @version    1.1, 9/27/96
 * @author     Mark Grand
 */
</PRE>
</DIV>

<P CLASS=para>
Here are the special documentation comment tags recognized
by <I CLASS=emphasis>javadoc</I> :

<P>
<DL CLASS=variablelist>
<DT CLASS=varlistentry><tt CLASS=literal>@author author-name</tt><br>
<DD>

<P CLASS=para>
Formats the given author name. This
tag can only be used in a class or interface documentation comment.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@exception name description</tt><br>
<DD>

<P CLASS=para>
Formats the given exception name and
its description in the throws section of a method description.
The name should be the fully qualified class name of the exception.
This tag can only be used in a method documentation comment.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@param name description</tt><br>
<DD>

<P CLASS=para>
Formats the given parameter name and
its description in the parameters section of a method description.
This tag can only be used in a method documentation comment.

<DT CLASS=varlistentry><tt CLASS=literal>@return description</tt><br>
<DD>

<P CLASS=para>
Formats the given description in the
returns section of a method description. This tag can only be used
in a method documentation comment.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@see classname</tt><br>
<DD>

<P CLASS=para>
Generates a hypertext link to the specified
class. The class name may be qualified by its package name.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@see classname#method-name</tt><br>
<DD>

<P CLASS=para>
Generates a hypertext link to the specified
method in the specified class. The class name may be qualified
by its package name.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@version text</tt><br>
<DD>

<P CLASS=para>
Formats the given text as version information.
This tag can only be used in a class or interface documentation comment.

<p>
<DT CLASS=varlistentry><tt CLASS=literal>@deprecated</tt><br>
<DD>

<P CLASS=para>
Indicates that a class, method, or variable is deprecated, which means
that it has been superceded by a newer, preferred class, method, or
variable. Deprecated features should not be used in new Java programs.
In addition, you should try to update existing code so that it does
not rely on deprecated features.  While the
deprecated features in Java 1.1 are still supported, there is no
guarantee that they will be supported in future releases. The 
<tt CLASS=literal>@deprecated</tt> tag is new as of Java 1.1.</DL>
<P CLASS=para>
The documentation comment that immediately
precedes a declaration is associated with the declaration. If two
comments precede a declaration, only the one immediately preceding
the declaration is processed by <I CLASS=emphasis>javadoc</I>. The
first comment is not considered to be associated with a declaration,
so it is ignored. If there is anything but white space between a
documentation comment and a declaration, the documentation comment
is not considered to be associated with the declaration.

<P CLASS=para>
<b>References</b>
<A HREF="ch02_02.htm#JLR2-CH-2-SECT-2.6">Comments</A>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch07_03.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch07_05.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>The import Directive</td>
<td width=171 align=center valign=top><a href="index/idx_0.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>Applications</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
